While BOSS is able to sort the large number of plugins listed in its masterlist without any user input, you may find that you wish to customise the sorting of your plugins. This may be to include plugins not listed in the masterlist (either plugins not yet added or temporary plugins or private files not suitable for masterlist inclusion), or it could be to rearrange plugins present in the masterlist that can be loaded in a different configuration for different results (eg. LAME and Supreme Magicka files). You may also wish to add extra messages to plugins, or edit existing messages.
One possible solution is to edit your copy of the masterlist to include the desired changes. However, as updating your masterlist will remove these edits, this is not very suitable as a long term solution.
This is where user rules come in. Using a separate userlist file, you can define rules for sorting specific plugins or groups of plugins as you like, as well as for adding or editing messages attached to plugins, and these rules will not be lost when you update your masterlist.
Note: This ReadMe refers to .esp and .esm files as 'plugins'. Unless explicitely stated, the 'name' of a 'plugin' refers to its filename, including the extension. Also, while the examples in this ReadMe reference Oblivion and some of its plugins, the functionality will work for all the games BOSS supports. When your game's master .ESM file is mentioned, this refers to Oblivion.esm, Nehrim.esm, Fallout3.esm or FalloutNV.esm for Oblivion, Nehrim, Fallout 3 or Fallout: New Vegas respectively.
The userlist is the file which contains your custom rules for sorting plugins and editing plugins' messages. It is found at BOSS\[GAME]\userlist.txt, where [GAME] is one of Oblivion, Nehrim, Skyrim, Fallout 3 or Fallout New Vegas, depending on the game the userlist is for. A blank userlist is automatically created for a game when BOSS is first run for that game.
Within this file, which you can edit in Notepad or any other text editor, you list your rule definitions. Rules can make two types of changes:
\BeginGroup\: Group Name and \EndGroup\\, or BEGINGROUP: Group Name and ENDGROUP, lines.
The rule definition syntax is simple and concise, and is explained below.
While it is strongly suggested that you read the Rule Definition Syntax section below to gain a proper understanding of user rules, here is a quick start guide for some simple rules.
To sort a plugin that is not in the masterlist after another plugin:
ADD: [RULE PLUGIN]
AFTER: [SORT PLUGIN]
To sort it before another plugin:
ADD: [RULE PLUGIN]
BEFORE: [SORT PLUGIN]
The rule plugin is the plugin you want to add, and the sort plugin is the plugin you want to sort it relative to.
Examples:
ADD: Plugin1.esp
AFTER: AFK_Weye.esp
ADD: Plugin2.esp
BEFORE: AFK_Weye.esp
This gives a load order of:
...
Plugin2.esp
AFK_Weye.esp
Plugin1.esp
...
To sort a plugin that is already in the masterlist after another plugin:
OVERRIDE: [RULE PLUGIN]
AFTER: [SORT PLUGIN]
To sort it before another plugin:
OVERRIDE: [RULE PLUGIN]
BEFORE: [SORT PLUGIN]
The rule plugin is the plugin you want to sort, and the sort plugin is the plugin you want to sort it relative to.
Example:
OVERRIDE: bgBalancingEVCore.esp
AFTER: Unofficial Oblivion Patch.esp
This gives a load order of:
...
Unofficial Oblivion Patch.esp
bgBalancingEVCore.esp
...
To add a message to a plugin for display in the BOSS Log:
FOR: [RULE PLUGIN]
APPEND: [MESSAGE OBJECT]
To replace the messages attached to a plugin for display in the BOSS Log:
FOR: [RULE PLUGIN]
REPLACE: [MESSAGE OBJECT]
The rule plugin is the plugin you want to add the message to. The message object is the formatted BOSS message that you want to attach. See the The BOSS Message Format section later on in this readme if you are unfamiliar with BOSS message formatting.
An example:
FOR: Unofficial Oblivion Patch.esp
REPLACE: ? Replaced!
FOR: bgMagicEV.esp.esp
APPEND: % {{BASH:Names,Delev,Relev}}
This will print in the BOSS Log:
...
Unofficial Oblivion Patch.esp...
- Note: Replaced!
bgMagicEV.esp.esp...
- Bashed Patch tag suggestion: {{BASH:Names,Delev,Relev}}
User rules have a specific structure and syntax which your rules must follow to be applied. The information below provides the details on this structure and syntax.
Every rule begins with a rule line, which defines what basic type of rule it is and what plugin it is applied to. It has the structure:
[RULE KEYWORD]: [RULE OBJECT]
This is the rule line. The rule keyword can be one of:
The rule object is the plugin or group that the rule is applied to. If the rule keyword is ADD or FOR, the rule object must be a plugin.
When you define groups, the names of those groups are used as they appear in the masterlist. For example,
if you wanted to reference the group of plugins that begins with \BeginGroup\: Supreme Magicka, you would put it in the rule as Supreme Magicka.
There is one more keyword that can be used on the rule line. DISABLE can be put before the rule keyword to prevent the rule from being applied. For example:
DISABLE ADD: MyMod.esp
AFTER: Unofficial Oblivion Patch.esp
Would result in MyMod.esp not being sorted after Unofficial Oblivon Patch.esp. The DISABLE keyword should be used instead of silent comments to stop a rule being applied because the latter makes the rule invisible to the GUI's User Rule Editor whereas the former does not.
If a rule's rule keyword is ADD or OVERRIDE, it can sort plugins and should include a sort line directly below the rule line. If the rule keyword is FOR, the rule must not include a sort line. A rule may only contain one sort line. The sort line has the structure:
[SORT KEYWORD]: [SORT OBJECT]
The sort keyword can be one of:
When using the BEFORE or AFTER sort keywords, the sort object is the plugin or group that you wish the rule object to be positioned relative to. Plugins must be sorted relative to other plugins, and groups must be sorted relative to groups. You cannot sort plugins relative to groups, or vice versa. You also cannot sort your game's master .ESM, sort other plugins before it, or sort groups before the "ESMs" group.
When using the TOP or BOTTOM sort keywords, the sort object is the group that you wish to insert the rule plugin into. You cannot insert groups into anything, plugins into plugins, or insert anything into the top of the ESMs
group.
If a rule's rule keyword is FOR, it should include at least one message line. A rule with a rule keyword of ADD or OVERRIDE can also include message lines, if they sort a plugin. Message lines have the structure:
[MESSAGE KEYWORD]: [MESSAGE OBJECT]
The message keyword can be one of:
REPLACE message line per rule, and if used it must be the first message line.
The message object is the message, complete with symbol code, that you wish to attach to the plugin defined by the rule object. You cannot attach messages to groups.
You may have multiple message lines in a rule (but only the first may use the REPLACE message keyword), to add multiple messages to a plugin, or to override an existing set of messages with a new set.
Here is the contents of an example userlist:
ADD: MyPluginToAdd.esp
AFTER: LoadAfterThis.esm
APPEND: ? Adding a general message.
APPEND: $ Incompatible with OOO!
OVERRIDE: MyPluginToOverride.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: L.A.M.E.
BEFORE: Supreme Magicka
FOR: bgBalancingEVOptionalNPCDiversity, Vanilla.esp
REPLACE: ? This is a replacement message.
APPEND: % {{BASH:NpcFaces,NoMerge}}
This is the equivalent of the masterlist having:
...
LoadAfterThis.esm
MyPluginToAdd.esp
? Adding a general message.
$ Incompatible with OOO!
...
MyPluginToOverride.esp
LoadBeforeThis.esp
...
bgBalancingEVOptionalNPCDiversity, Vanilla.esp
? This is a replacement message.
% {{BASH:NpcFaces,NoMerge}}
...
Which would give in the BOSS Log:
...
LoadAfterThis.esm
MyPluginToAdd.esp...
- Note: Adding a general message.
- Note: Incompatible with OOO!
MyPluginToOverride.esp
LoadBeforeThis.esp
...
bgBalancingEVOptionalNPCDiversity, Vanilla.esp...
- Note: This is a replacement message.
- Bash Tag Suggestion(s): {{BASH:NpcFaces,NoMerge}}
The rule sorting the two groups L.A.M.E. and Supreme Magicka simply moves the L.A.M.E. group from its current position to before the Supreme Magicka group.
When BOSS is run, it will look for your userlist at BOSS\[GAME]\userlist.txt, where [GAME] is one of Oblivion, Nehrim, Skyrim, Fallout 3 or Fallout New Vegas, depending on the game BOSS is running for. If it is found, and the userlist contains at least one rule, BOSS will first check the syntax of the rules, and apply those with the correct syntax.
It will print error messages detailing the problems with any rules it skips, and success messages for the plugins that are applied, into your BOSS Log, in the Userlist Messages
section near the top. Disabled rules have their syntax checked, but are not applied.
If a rule is successfully applied, it will print one or more messages depending on what the rule does:
"Plugin/Group Name" sorted before/after "Plugin/Group Name".
"Plugin Name" inserted into the top/bottom of group "Group Name".
"Message" appended to/replaced messages attached to "Plugin Name".
If the parser finds a major grammatical error in your userlist, it will stop parsing and discard any rules it has found before printing an error message detailing what was expected and where. In some cases, the expected item may not provide much useful meaning - in these cases look at where the error was found and determine the exact cause of the problem yourself.
If a rule is found to have errors in its syntax, it will be skipped and an error message of the form: Syntax Error: The rule beginning "First Line Of Rule" details of error will be printed to your BOSS Log. See the main BOSS ReadMe for a full list of possible syntax errors.
If an error is encountered while trying to apply a rule, it will be skipped and an error message detailing the fault will be printed to your BOSS Log.
Rule application does not alter your masterlist.txt or userlist.txt. This means that if you want to undo the application of a rule, all you need to do is remove it from your userlist.txt (or disable it) and re-run BOSS.
While the Rule Definition Syntax section gave you most of the rules of defining rules, here are some further general notes on defining rules that may not be evident:
// in your userlist will be ignored by BOSS. You can use blank lines to improve the formatting of your userlist, and use the // line start to provide comments or disable specific rules as you desire.
\ instead of // to have the same effect, and comment out multiple lines by enclosing them between /* and */.
DISABLE keyword to disable rules, as this means that they are still visible to the GUI's User Rule Editor without being applied. Rules with incorrect syntax should be commented out, as disabled rules are still parsed with error checking.
ESMify Selffunction, which makes a plugin into a master without changing the file extension.)
Rules are applied in the order they are listed. This means you can have several rules sorting different rule objects relative to the same sort object, or have rules sorting rule objects relative to sort objects that were sorted in previous rules.
For example:
ADD: LoadBeforeThis.esp
AFTER: RTT.esp
ADD: Plugin1.esp
BEFORE: LoadBeforeThis.esp
OVERRIDE: xulAspenWood.esp
AFTER: Plugin1.esp
ADD: Plugin2.esp
BEFORE: RTT.esp
which will order the plugins as:
Plugin2.esp
RTT.esp
Plugin1.esp
xulAspenWood.esp
LoadBeforeThis.esp
Take care when writing such rules though, as a small difference in the order of the rules in your userlist can have a very large difference on the resulting load order.
Understanding the BOSS message format is important if you wish to edit plugins' messages. There are actually two formats, either of which may be used. Each of the four message types that can be added via the userlist begins with a message symbol or message keyword depending on the format used. The symbol/keyword is then followed by the message itself. The message is just a standard line of text. In addition, Bash Tag suggestion messages also have a special syntax for the suggestions they include.
The message message types, symbols and keywords are listen in the table below:
| Message Type | Format 1 Symbol | Format 2 Keyword |
| Bash Tag Suggestion | % | TAG: |
| General Message | ? | SAY: |
| Installation Requirement | : | REQ: |
| Specific Incompatibility | " | INC: |
The syntax for a Bash Tag suggestion is:
% {{BASH:list suggested tags separated by ", " here}} you may also have some text here.
or:
TAG: {{BASH:list suggested tags separated by ", " here}} you may also have some text here.
For example:
% {{BASH:Names, Graphics}} to prevent changes being lost when using overhauls.
You can also mix the two formats, giving one message in one format and another message in the other. You are not restricted to using only one format.
This document is part of the BOSS documentation.
Copyright (C) 2011 BOSS Development Team.
See the file BOSS ReadMe.html
for copying conditions.